Windows Standard Communications Library for Delphi (WSC4D) REFERENCE MANUAL Version 2.4 June 7, 1999 This software is provided as-is. There are no warranties, expressed or implied. Copyright (C) 1996-1999 All rights reserved MarshallSoft Computing, Inc. Post Office Box 4543 Huntsville AL 35815 Voice : 256-881-4630 FAX : 256-880-0925 email : info@marshallsoft.com web : www.marshallsoft.com _______ ____|__ | (R) --+ | +------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals --+--+ | +--------------------- |___|___| MEMBER MARSHALLSOFT is a registered trademark of MarshallSoft Computing. WSC4D Reference Manual Page 1 C O N T E N T S Chapter Page Table of Contents.............................2 WSC Functions.................................4 SioBaud....................................4 SioBrkSig..................................4 SioCTS.....................................5 SioDCD.....................................5 SioDone....................................6 SioDSR.....................................6 SioDTR.....................................7 SioEvent...................................7 SioFlow....................................8 SioGetc....................................8 SioGets....................................9 SioInfo....................................9 SioParms..................................10 SioPutc...................................10 SioPuts...................................11 SioRead...................................11 SioReset..................................12 SioRI.....................................12 SioRTS....................................13 SioRxClear................................13 SioRxQue..................................14 SioStatus.................................14 SioTimer..................................15 SioTxClear................................15 SioTxQue..................................16 SioUnGetc.................................16 SioWinError...............................17 WSC Error Codes..............................17 WSC4D Reference Manual Page 2 C O N T E N T S (continued) Chapter Page Modem I/O Functions mioBreak..................................18 mioDriver.................................18 mioQuiet..................................19 mioResult.................................19 mioSendTo.................................20 mioWaitFor................................20 Xmodem/Ymodem Driver (XYDRV) Functions xyAbort...................................21 xyAcquire.................................21 xyDebug...................................22 xyDriver..................................22 xyGetFileName.............................23 xyGetMessage..............................23 xyGetParameter............................24 xyRelease.................................24 xySetParameter............................25 xyStartRx.................................25 xyStartTx.................................26 XYDRV Error Codes.........................27 ASCII Driver (ASDRV) Functions ascAbort..................................28 ascDriver.................................28 ascGetMessage.............................29 ascGetParameter...........................29 ascInit...................................30 ascStartRx................................30 ascStartTx................................31 ASDRV Error Codes.........................31 WSC4D Reference Manual Page 3 +-------------+-----------------------------------------------------+ | SioBaud | Sets the baud rate. | +-------------+-----------------------------------------------------+ SYNTAX function SioBaud(Port,BaudCode:Integer):Integer; (* Port : Port selected. *) (* BaudCode : Baud code or actual baud rate. *) REMARK The SioBaud function sets the baud rate without resetting the port. It is used to change the baud rate after calling SioReset. SioBaud may be called with either the actual baud rate value or one of the baud rate codes as follows: Code Rate Name Code Rate Name 0 300 Baud300 5 9600 Baud9600 1 600 Baud600 6 19200 Baud19200 2 1200 Baud1200 7 38400 Baud38400 3 2400 Baud2400 8 57600 Baud57600 4 4800 Baud4800 9 115200 Baud115200 RETURN IE_BADID : No such port. IE_BAUDRATE : Unsupported baud rate. OTHER See SioReset. +-------------+-----------------------------------------------------+ | SioBrkSig | Asserts, cancels, or detects BREAK signal. | +-------------+-----------------------------------------------------+ SYNTAX function SioBrkSig(Port:Integer;Cmd:Char):Integer; (* Port : Port selected. *) (* Cmd : ASSERT, CANCEL, or DETECT. *) REMARK The SioBrkSig function controls the BREAK bit in the line status register. The legal commands are: ASSERT_BREAK : 'A' to assert BREAK CANCEL_BREAK : 'C' to cancel BREAK DETECT_BREAK : 'D' to detect BREAK ASSERT_BREAK, CANCEL_BREAK, and DETECT_BREAK are defined in WSC4D.PAS. See MODEM.C for an example of the use of SioBrkSig. RETURN IE_NOPEN : Port not opened. Call SioReset first. IE_BADID : No such port. WSC_RANGE : Illegal command. Expected 'A', 'C', or 'D'. >0 : BREAK signal detected (DETECT command only) OTHER See SioBrkKey. WSC4D Reference Manual Page 4 +-------------+-----------------------------------------------------+ | SioCTS | Reads the Clear to Send (CTS) modem status bit. | +-------------+-----------------------------------------------------+ SYNTAX function SioCTS(Port:Integer):Integer; (* Port : Port selected. *) REMARK The SioCTS function is used to detect if CTS (Clear To Send) is set (1) or clear (0). Some Windows Win16 COMM drivers cannot read the CTS bit correctly! The CTS line is used by some error correcting modems to implement hardware flow control. CTS is dropped by the modem to signal the computer not to send data and is raised to signal the computer to continue. Refer to the RS232/485 Serial Communications User's Manual (ASYNC.TXT) for a discussion of flow control. RETURN IE_NOPEN : Port not opened. Call SioReset first. IE_BADID : No such port. 0 : CTS is clear. >0 : CTS is set. OTHER See SioFlow, SioDSR, SioRI, SioDCD. +-------------+-----------------------------------------------------+ | SioDCD | Reads the Data Carrier Detect (DCD) modem staus bit| +-------------+-----------------------------------------------------+ SYNTAX function SioDCD(Port:Integer):Integer; (* Port : Port selected. *) REMARK The SioDCD function is used to read the Data Carrier Detect (DCD) modem status bit. RETURN IE_NOPEN : Port not opened. Call SioReset first. IE_BADID : No such port. 0 : DCD is clear. >0 : DCD is set. OTHER See SioDSR, SioCTS, SioRI. WSC4D Reference Manual Page 5 +-------------+-----------------------------------------------------+ | SioDone | Terminates further serial processing. | +-------------+-----------------------------------------------------+ SYNTAX function SioDone(Port:Integer):Integer; (* Port : Port selected. *) REMARK The SioDone function terminates further serial processing, allowing other applications to use the port. The SioDone function leaves the state of DTR and RTS the same as before SioReset was called. RETURN IE_NOPEN : Port not opened. Call SioReset first. IE_BADID : No such port. OTHER See SioReset. +-------------+-----------------------------------------------------+ | SioDSR | Reads the Data Set Ready (DSR) modem status bit. | +-------------+-----------------------------------------------------+ SYNTAX function SioDSR(Port:Integer):Integer; (* Port : Port selected. *) REMARK The SioDSR function is used to detect if DSR (Data Set Ready) is set (1) or clear (0). Some Windows Win16 COMM drivers cannot read the DSR bit correctly! RETURN IE_NOPEN : Port not opened. Call SioReset first. IE_BADID : No such port. 0 : DSR is clear. >0 : DSR is set. OTHER See SioCTS, SioRI, and SioDCD. WSC4D Reference Manual Page 6 +-------------+-----------------------------------------------------+ | SioDTR | Set, clear, or read Data Terminal Ready (DTR). | +-------------+-----------------------------------------------------+ SYNTAX function SioDTR(Port:Integer;Cmd:Char):Integer; (* Port : Port selected. *) (* Cmd : DTR command (see below). *) REMARK The SioDTR function controls the Data Terminal Ready (DTR) bit in the modem control register. DTR should always be set when communicating with a modem. Commands (defined in WSC4D.PAS): SET_LINE : 'S' to set DTR (ON) CLEAR_LINE : 'C' to clear DTR (OFF) READ_LINE : 'R' to read DTR RETURN IE_NOPEN : Port not opened. Call SioReset first. IE_BADID : No such port. WSC_RANGE : Not one of 'S', 'C', or 'R'. 0 : DTR is clear (READ_LINE Command). >0 : DTR is set (READ_LINE Command). OTHER See SioRTS. +-----------+-------------------------------------------------------+ | SioEvent | Efficiently waits for serial event. | +-----------+-------------------------------------------------------+ SYNTAX function SioEvent(Port:Integer; Mask:Word):Integer; (* Port : Port selected. *) (* Mask : Event Mask [see below].*) REMARK The SioEvent function (WIN32 only) waits (blocks) until the condition specfied in 'Mask' is satisfied. Multiple conditions can be OR'ed together. The event masks are: EV_RXCHAR : A character was received. EV_BREAK : A break signal was received. EV_CTS : The CTS line changed states. EV_DSR : The DST line changed states. EV_ERR : An error was detected. EV_RLSD : The DCD line has changed states. EV_RING : The RI line has been set. EV_TXEMPTY : The TX queue has become empty. RETURN SioEvent does not return until the specified event occurs. OTHER See SioRead. WSC4D Reference Manual Page 7 +------------+------------------------------------------------------+ | SioFlow | Sets hardware (RTS/CTS) flow control. | +------------+------------------------------------------------------+ SYNTAX function SioFlow(Port:Integer;Cmd:Char):Integer; (* Port : Port selected. *) (* Cmd : Class of flow control (see below). *) REMARK The SioFlow function is used to enable or disable hardware or software flow control. Hardware flow control uses RTS and CTS to control data flow between the modem and the computer. To enable flow control, call SioFlow with 'Cmd' set to: Cmd Flow Control 'H' Hardware (RTS/CTS) flow control. 'S' Software (XON/XOFF) flow control. 'N' No flow control. In order for hardware flow control to work correctly, your modem must also be configured to work with hardware flow control, and your computer to modem cable must have RTS and CTS wired straight through. If you enable hardware flow control, do not modify the RTS line (by calling SioRTS). Flow control is disabled after resetting a port. RETURN IE_NOPEN : Port not opened. Call SioReset first. IE_BADID : No such port. WSC_RANGE : Cannot recognize Cmd. -1 : Flow control disabled. >0 : Flow control enabled. OTHER See SioPutc +------------+------------------------------------------------------+ | SioGetc | Reads the next character from the serial line. | +------------+------------------------------------------------------+ SYNTAX function SioGetc(Port:Integer) (* Port : Port selected. *) REMARK The SioGetc function reads a byte from the selected serial port. WSC_NO_DATA (-100) is returned if no byte is available. RETURN IE_NOPEN : Port not opened. Call SioReset first. IE_BADID : No such port. WSC_NO_DATA : If timed out (no data available). >= 0 : Character read. OTHER See SioUnGetc and SioGets. WSC4D Reference Manual Page 8 +------------+------------------------------------------------------+ | SioGets | Reads the next byte buffer from the serial line. | +------------+------------------------------------------------------+ SYNTAX function SioGets(Port:Integer; Buffer:PChar; Cnt:Word):Integer; (* Port : Port selected. *) (* Buffer : Receive buffer. *) (* Cnt : Number bytes to read. *) REMARK The SioGets function reads the smaller of the number of bytes wanted (Cnt) and the number of bytes in the receive buffer. A zero is return if no bytes are read. Refer to EVNT_PGM.PAS for an example. RETURN IE_NOPEN : Port not opened. Call SioReset first. IE_BADID : No such port. >= 0 : Number of characters actually read. OTHER See SioUnGetc and SioPutc. See the EVENT example program for an programming example. +-------------+-----------------------------------------------------+ | SioInfo | Returns WSC4D library information. | +-------------+-----------------------------------------------------+ SYNTAX function SioInfo(Cmd:Integer):Integer; (* Cmd : Command (See below). *) REMARK The SioInfo function returns an integer code corresponding to the 'Cmd' as follows: Command SioInfo returns 'V' Library version number (3 digits D1.D2.D3). Code := SioInfo('V'); D3 := $0F AND Code; Code := Code SHR 4; D2 := $0F AND Code; Code := Code SHR 4; D1 := $0F AND Code; VersionText := Chr(48+D1) + '.' + Chr(48+D2) + '.' + Chr(48+D3); RETURN See remarks above. -1 : Cannot recognize command 'Cmd'. WSC4D Reference Manual Page 9 +-------------+-----------------------------------------------------+ | SioParms | Sets parity, stop bits, and word length. | +-------------+-----------------------------------------------------+ SYNTAX function SioParms(Port,Parity,StopBits, DataBits:Integer):Integer; (* Port : Port selected. *) (* Parity : Parity code. *) (* StopBits : Stop bits code. *) (* DataBits : Word length code. *) REMARK The SioParms function sets the parity, stop bits, and word length. If the default parity (none), stop bits (1), or word length (8) is not acceptable, then they can be changed by calling SioParms. SioParms can be called either before or after calling SioReset. See file WSC4D.PAS. Use the constant values defined in WSC4D.PAS to minimize the chance of passing an incorrect parameter value. Parity : NoParity, OddParity, EvenParity, MarkParity, SpaceParity. StopBits : OneStopBit, One5StopBits, TwoStopBits. DataBits : WordLength7, WordLength8. RETURN IE_BADID : No such port. IE_BYTESIZE : Word length not supported. WSC_RANGE : Parameter out of range. OTHER See SioReset. +-------------+-----------------------------------------------------+ | SioPutc | Transmit a character over a serial line. | +-------------+-----------------------------------------------------+ SYNTAX function SioPutc(Port:Integer;Ch:Char):Integer; (* Port : Port selected. *) (* Ch : Character to send. *) REMARK The SioPutc function copies the character to the transmit queue for subsequent transmission. RETURN IE_NOPEN : Port not opened. Call SioReset first. IE_BADID : No such port. 0 : No error. OTHER See SioGetc and SioFlow. WSC4D Reference Manual Page 10 +-------------+-----------------------------------------------------+ | SioPuts | Transmits a byte buffer over a serial line. | +-------------+-----------------------------------------------------+ SYNTAX function SioPuts(Port:Integer; Buffer:PChar; Cnt:Word):Integer; (* Port : Port selected. *) (* Buffer : String of bytes to transmit. *) (* Cnt : Number of bytes to send. *) REMARK The SioPuts function copies 'Cnt' characters from 'Buffer' to the transmit queue for subsequent transmission. Refer to EVNT_PGM.PAS for an example. RETURN IE_NOPEN : Port not opened. Call SioReset first. IE_BADID : No such port. >= 0 : The number of bytes accepted by TX queue. OTHER See SioGetc and SioFlow. +-------------+-----------------------------------------------------+ | SioRead | Reads any UART register. | +-------------+-----------------------------------------------------+ SYNTAX function SioRead(Port, Reg : Integer) : Integer; (* Port : Port selected. [COM1 to COM4] *) (* Reg : UART register [0 to 7]. *) REMARK SioRead is NOT for Win32 applications running under Windows NT. The SioRead function reads any of the 7 I/O ports directly, by-passing the Windows API. Note that all modem and/or line status bits can also be read using SioDTR, SioRTS, SioDCD, SioRI, SioDSR, and SioCTS. Refer to the RS232 Manual for a description of the UART registers. RETURN IE_NOPEN : Port not opened. Call SioReset first. IE_BADID : No such port. >0 : Contents of selected UART register. OTHER Not for Win32 applications running under Win NT. Also see SioStatus. WSC4D Reference Manual Page 11 +-------------+-----------------------------------------------------+ | SioReset | Initialize a serial port for processing. | +-------------+-----------------------------------------------------+ SYNTAX function SioReset(Port,RxQueSize,TxQueSize:Integer):Integer; (* Port : Port selected. *) (* RxQueSize : Receive queue size. *) (* TxQueSize : Transmit queue size. *) REMARK The SioReset function initializes the selected serial port. SioReset should be called before making any other calls to WSC4D. SioReset uses the parity, stop bits, and word length value previously set if SioParm was called, otherwise the default values (see SioParm) are used. RETURN IE_BADID : No such port. IE_OPEN : Already open. IE_MEMORY : Cannot allocate memory. IE_HARDWARE : Hardware error. OTHER See SioBaud, SioParms, and SioDone. +-------------+-----------------------------------------------------+ | SioRI | Reads the Ring Indicator (RI) modem status bit. | +-------------+-----------------------------------------------------+ SYNTAX function SioRI(Port:Integer) (* Port : Port selected. *) REMARK The SioRI function is used to read the Ring Indicator (RI) modem status bit. RETURN IE_NOPEN : Port not opened. Call SioReset first. IE_BADID : No such port. 0 : RI is clear. >0 : RI is set (RING has occurred). OTHER See SioDSR, SioCTS, and SioDCD. WSC4D Reference Manual Page 12 +-------------+-----------------------------------------------------+ | SioRTS | Sets, clears, or reads the Request to Send (RTS). | +-------------+-----------------------------------------------------+ SYNTAX function SioRTS(Port:Integer;Cmd:Integer):Integer; (* Port : Port selected. *) (* Cmd : RTS command. *) REMARK The SioRTS function controls the Request to Send (RTS bit in the modem control register. The RTS line is used by some error correcting modems to implement hardware flow control. RTS is dropped by the computer to signal the modem not to send data, and is raised to signal the modem to continue. RTS should be set when communicating with a modem unless Flow Control is being used. Refer to the RS232/485 Serial Communications User's Manual (ASYNC.TXT) for a discussion of flow control. Commands (defined in WSC16.PAS and WSC32.PAS) are: SET_LINE 'S' : set RTS (ON) CLEAR_LINE 'C' : clear RTS (OFF) READ_LINE 'R' : read RTS RETURN IE_NOPEN : Port not opened. Call SioReset first. IE_BADID : No such port. WSC_RANGE : Command is not one of 'S', 'C', or 'R'. 0 : RTS is clear ('R' command). >0 : RTS is set ('R' command). OTHER See SioFlow and SioDTR. +------------+------------------------------------------------------+ | SioRxClear | Clears the receive buffer. | +------------+------------------------------------------------------+ SYNTAX function SioRxClear(Port:Integer) (* Port : Port selected. *) REMARK The SioRxClear function will delete any characters in the receive buffer for the specified port. After execution, the receive buffer will be empty. RETURN IE_NOPEN : Port not opened. Call SioReset first. IE_BADID : No such port. OTHER See SioRxQue. WSC4D Reference Manual Page 13 +-------------+-----------------------------------------------------+ | SioRxQue | Returns the number of bytes in the receive queue. | +-------------+-----------------------------------------------------+ SYNTAX function SioRxQue(Port:Integer) (* Port : Port selected. *) REMARK The SioRxQue function will return the number of characters in the receive queue at the time of the call. RETURN IE_NOPEN : Port not opened. Call SioReset first. IE_BADID : No such port. OTHER See SioTxQue +------------+------------------------------------------------------+ | SioStatus | Returns the serial port status. | +------------+------------------------------------------------------+ SYNTAX function SioStatus(Port:Integer;Mask:Word):Integer; (* Port : Port selected. *) (* Mask : Error mask. *) REMARK The SioStatus function returns the serial port error status corresponding to the Mask argument. WSC_RXOVER : The receive queue overflowed. WSC_OVERRUN : An incoming byte was overwritten. WSC_PARITY : A parity error was detected (incoming byte) WSC_FRAME : A framing error was detected (incoming byte) WSC_BREAK : A break signal was detected. WSC_TXFULL : The transmit queue is full. For example, to test for receive queue overflow: if(SioStatus(Port, WSC_RXOVER)) printf(.RX Overflow.); The nummerical values of the mask constants are defined in WSC16.PAS and WSC32.PAS. RETURN IE_NOPEN : Port not opened. Call SioReset first. IE_BADID : No such port. WSC4D Reference Manual Page 14 +-----------+-------------------------------------------------------+ | SioTimer | Returns the system time in milliseconds. | +-----------+-------------------------------------------------------+ SYNTAX function SioTimer: LongInt; REMARK The SioTimer function returns the system in milliseconds. Its primary purpose is to compute the time between two events. RETURN The system time in milliseconds. +------------+------------------------------------------------------+ | SioTxClear | Clears the transmitter buffer. | +------------+------------------------------------------------------+ SYNTAX function SioTxClear(Port:Integer) (* Port : Port selected. *) REMARK The SioTxClear function will delete any characters in the transmit buffer for the specified port. Once this function is called, any character in the transmit buffer (put there by SioPutc or SioPuts) will be lost and therefore not transmitted. RETURN IE_NOPEN : Port not opened. Call SioReset first. IE_BADID : No such port. OTHER See SioTxQue WSC4D Reference Manual Page 15 +------------+------------------------------------------------------+ | SioTxQue | Returns the number of bytes in the transmit queue. | +------------+------------------------------------------------------+ SYNTAX function SioTxQue(Port:Integer) (* Port : Port selected. *) REMARK The SioTxQue function will return the number of characters in the transmit queue at the time of the call. RETURN IE_NOPEN : Port not opened. Call SioReset first. IE_BADID : No such port. OTHER See SioRxQue +------------+-----+------------------------------------------------+ | SioUnGetc | 'Un|gets' the last character read with SioGetc(). | +------------+-----+------------------------------------------------+ SYNTAX function SioUnGetc(Port:Integer;Ch:Char):Integer; (* Port : Port selected. *) (* Ch : Character to unget. *) REMARK The SioUnGetc function returns (pushes) the character back into the serial input buffer. The character pushed will be the next character returned by SioGetc. Only one character can be pushed back. This function works just like the "ungetc" function in the C language. RETURN IE_NOPEN : Port not opened. Call SioReset first. IE_BADID : No such port. OTHER See SioReset. WSC4D Reference Manual Page 16 +--------------+----------------------------------------------------+ | SioWinError | Return last Win32 error code & message text. | +--------------+----------------------------------------------------+ SYNTAX function SioWinError(Buffer:PChar; Size:LongInt):Integer; (* Buffer : Pointer to messages buffer. *) (* Size : Size of buffer. *) REMARK The SioWinError returns the last Win32 error code. If Buffer is not NULL, it will also copy the corresponding text message into 'Buffer' of size 'Size'. RETURN The Win32 numeric error code. WSC Error Codes +---------------+---------------------------------------------+ | WSC_NO_DATA | No incoming serial data is available. | | WSC_RANGE | A parameter is out of range. | | WSC_ABORTED | The shareware version of WSC corrupted. | | WSC_WIN32ERR | Win32 system error. | +---------------+---------------------------------------------+ | IE_BADID | No such port. | | IE_OPEN | Port already opened. | | IE_NOPEN | Port not opened. Call SioReset first. | | IE_MEMORY | Cannot allocate memory for queues. | | IE_DEFAULT | Error in default parameters. | | IE_HARDWARE | Hardware not present. | | IE_BYTESIZE | Unsupported byte size. | | IE_BAUDRATE | Unsupported baud rate. | +---------------+---------------------------------------------+ The WSC_ABORTED error occurs in the shareware version only if there is a problem displaying the shareware screen. The WSC_WIN32ERR error code is returned only for Win32 system errors. Call SioError to format the textual error message. WSC4D Reference Manual Page 17 +-----------+-------------------------------------------------------+ | mioBreak | Aborts the Modem I/O state driver. | +-----------+-------------------------------------------------------+ SYNTAX function mioBreak(Port:Integer):Integer; (* Port : Port selected. *) REMARK Forces the MIO driver to the IDLE state, abandoning any work in progress (if any). Used to abort mioSendTo, mioQuiet, and mioWaitFor functins. RETURN MIO_IDLE. +------------+------------------------------------------------------+ | mioDriver | Modem I/O state driver. | +------------+------------------------------------------------------+ SYNTAX function mioDriver(Port:Integer):Integer; (* Port : Port selected. *) REMARK Executes the next state of any previously started MIO function such as mioSendTo, mioWaitFor, and mioQuiet. Returns MIO_IDLE (defined in MIO.PAS) if not running, MIO_RUNNING if running, and anything else is a character from the modem that can be displayed if wanted. RETURN MIO_IDLE : if the driver is ready for the next mioSendTo, mioWaitFor, or mioQuiet. MIO_RUNNING : if the driver is not idle. : if the driver is not idle, and the returned character was received from the modem. WSC4D Reference Manual Page 18 +-----------+-------------------------------------------------------+ | mioQuiet | Waits for Modem I/O state driver. | * +-----------+-------------------------------------------------------+ SYNTAX function mioQuiet(Port:Integer;Wait:LongInt):Integer; (* Port : Port selected. *) (* Wait : Wait in milliseconds. *) REMARK The mioQuiet function waits for continuous quiet [no incoming serial data] of 'Wait' milliseconds before returning. Any incoming character while mioQuiet is running is lost. RETURN TRUE. +------------+------------------------------------------------------+ | mioResult | Returns result of last mioWaitFor. | +------------+------------------------------------------------------+ SYNTAX function mioResult(Port:Integer):Integer; (* Port : Port selected. *) REMARK The mioResult function returns the result of the last mioWaitFor function. This function should not be called until the driver returns MIO_IDLE. See the remarks section of the mioWaitFor function for an example. RETURN 0 : False (last WaitFor not matched) !0 : '0' if first substring matched, '1' if second substring matched, etc. OTHER See mioWaitFor. WSC4D Reference Manual Page 19 +-----------+-------------------------------------------------------+ | mioSendTo | Sends string to modem. | +-----------+-------------------------------------------------------+ SYNTAX function mioSendTo(Port:Integer;Pace:LongInt: Text:PChar):Integer; (* Port : Port selected. *) (* Pace : The inter-character delay in milliseconds. *) (* Text : The string to send. *) REMARK The mioSendTo function sends the characters in the string 'Text' to serial output. There is a delay of 'Pace' milliseconds between characters. Three characters in 'Text' are interpreted as: '^' : next character is control char (^A for 0x01) '!' : replaced with carriage return. '~' : removed from string (delay 1/2 second). RETURN TRUE. +-------------+-----------------------------------------------------+ | mioWaitFor | Waits for continuous quiet. | +-------------+-----------------------------------------------------+ SYNTAX function mioWaitFor(Port:Integer;Wait:LongInt; Text:PChar):Integer; (* Port : Port selected. *) (* Wait : Total time to wait for response (milliseconds). *) (* Text : The expected response string. *) REMARK The mioWaitFor function waits for characters from serial input that match the string 'Text'. A total of 'Wait' milliseconds are allowed before timing out and returning FALSE (0). The string comparison is NOT case sensitive. For example, to wait up to one minute for 'CONNECT', 'NO CARRIER', or 'BUSY' from the modem after dialing a number. Code = mioWaitFor(Port,60000,'CONNECT|NO CARRIER|BUSY') The function mioDriver() must be called until MIO_IDLE is returned. Then mioResult() is called to get the result of the mioWaitFor. A value of 0 indicates that neither 'CONNECT', 'BUSY', nor 'NO CARRIER' was received. A non-zero value indicates that one of the three sub-strings was received. A '0' is returned if 'CONNECT' was seen, '1' is returned if 'NO CARRIER' was seen, and '2' is returned if 'BUSY' was seen. RETURN TRUE. OTHER See mioResult. WSC4D Reference Manual Page 20 +---------+------------------------------------------------------+--* | xyAbort | Aborts the XYDRV state driver. | +---------+------------------------------------------------------+--* SYNTAX function xyAbort(Port:Integer):Integer; (* Port : Port selected. *) REMARK The xyAbort function forces the driver to IDLE, terminating any file transfer which may be in progress. RETURN XY_NO_ERROR (0). +-----------+-------------------------------------------------------+ | xyAcquire | Prepares the state driver for operation. | +-----------+-------------------------------------------------------+ SYNTAX function xyAcquire(First:Integer;Last:Integer):Integer; (* First : First port selected. *) (* Last : Last port acquired. *) REMARK The xyAcquire function initializes the driver for subsequent use. This should be the first driver function called. RETURN =0 : No error (XY_NO_ERROR). <0 : XYDRV error. See "XYDRV Error Codes". OTHER See xyRelease. WSC4D Reference Manual Page 21 +----------+--------------------------------------------------------+ | xyDebug | Set the driver debug level. | +----------+--------------------------------------------------------+ SYNTAX function xyDebug(DebugLevel:Integer):Integer; (* DebugLevel : Debug level value. *) REMARK The xyDebug functions sets the driver debug level as follows: DebugLevel : Meaning 0 Only error messages are generated [default]. 1 Minimal debug messages are generated. 2 Maximal debug messages are generated. Debug messages are retrieved using the xyGetMessage function. RETURNs New debug level [0,1,2] +----------+--------------------------------------------------------+ | xyDriver | XMODEM / YMODEM state driver. | +----------+--------------------------------------------------------+ SYNTAX function xyDriver(Port:Integer):Integer; (* Port : Port selected. *) RETURN XY_IDLE : A transfer is not underway. XY_RUNNING : A transfer is underway. REMARK The xyDriver function drives the state engine. It is normally called within a timer loop. Note that xyDriver never returns an error code. xyDriver can be called as often as wanted whether or not a file transfer was initiated. OTHER See xyStartTx and xyStartRx. WSC4D Reference Manual Page 22 +---------------+---------------------------------------------------+ | xyGetFileName | Get current filename. | +---------------+---------------------------------------------------+ SYNTAX function xyGetFileName(Buffer:PChar;Size:Integer):Integer; (* Buffer : Filename buffer. *) (* Size : Size of filename buffer. *) REMARK The xyGetFileName function gets the filename of the file currently being transfered, if known. Typically used to get the filename of an incoming YMODEM transfer. RETURN TRUE : A message was copied into Buffer. FALSE : No messages are available. OTHER See xyGetParameter. +--------------+----------------------------------------------------+ | xyGetMessage | Get next Ascii driver message. | +--------------+----------------------------------------------------+ SYNTAX function xyGetMessage(Buffer:PChar;Size:Integer):Integer; (* Buffer : Message buffer. *) (* Size : Size of message buffer. *) REMARK The xyGetMessage function retieves the next message from the driver message queue. Refer to the TERM_PGM.PAS program for an example of using xyGetMessage. RETURN TRUE : A message was copied into Buffer. FALSE : No messages are available. OTHER See xyDebug. WSC4D Reference Manual Page 23 +----------------+--------------------------------------------------+ | xyGetParameter | Retrieves driver parameter. | +----------------+--------------------------------------------------+ SYNTAX function xyGetParameter(Port,Parameter:Integer):LongInt; (* Port : Port Selected. *) (* Parameter : Parameter to return. *) REMARK The driver parameter corresponding to the following table is returned. Parameter : Desciption XY_GET_ERROR_CODE : Driver error code (see XYDRV.PAS) XY_GET_ERROR_STATE : Error state (if in error). XY_GET_PACKET : Current packet number. XY_GET_STATE : Current state (see XYDRV.C). XY_GET_FILE_SIZE : File size. XY_GET_NBR_NAKS : Number of packets ACKed. XY_GET_LAST_GET : Last incoming (serial) character. XY_GET_LAST_PUT : Last outgoing (serial) character. XY_GET_GET_COUNT : Number of incoming characters (bytes). XY_GET_PUT_COUNT : Number of outgoing characters (bytes). XY_GET_DRIVER_COUNT : Number times xyDriver() was called. -1 : Cannot recognize parameter. The xyGetParameter function can be used to check the state of the driver. For example: (1) xyGetParameter(Port,XY_GET_STATE) returns XY_IDLE if idle. (2) xyGetParameter(Port,XY_GET_ERROR_CODE) returns the driver error code if an error has occurred or XY_NO_ERROR (0) otherwise. RETURN See above. +-----------+-------------------------------------------------------+ | xyRelease | Releases driver port. | +-----------+-------------------------------------------------------+ SYNTAX function xyRelease():Integer; REMARK The xyRelease function releases the ports that were previously acquired with xyAcquire. This function should be called before calling the WSC function SioDone. RETURN 0 : No error (XY_NO_ERROR). <0 : XYDRV error. See "XYDRV Error Codes". OTHER See xyAcquire. WSC4D Reference Manual Page 24 +----------------+--------------------------------------------------+ | xySetParameter | Retrieves driver parameter. | +----------------+--------------------------------------------------+ SYNTAX function xySetParameter(Port,ParmName,ParmValue:Integer) : LongInt (* Port : Port Selected *) (* ParmName : Parameter Name *) (* ParmValue : Parameter Value *) REMARK The ParmValue corresponding to the following table is set. ParmName : Description XY_SET_NAK_RATE : Sets the prompt delay (in seconds). XY_SET_EOF_CHAR : Sets the XMODEM pad character. -1 : Cannot recognize parameter. The XY_SET_NAK_RATE parameter sets the delay (in seconds) between prompts that the receiver transmits to the sender to start the file transfer. The legal range is 1 to 10 seconds. The XY_SET_EOF_CHAR parameter sets the pad character used by XMODEM in padding the last packet to 128 bytes. The normal value is control-Z (hex 1A). For example, to set the pad character to zeros: Code := xySetParameter(COM1, XY_SET_EOF_CHAR, 0) RETURN See above. WSC4D Reference Manual Page 25 +-----------+-------------------------------------------------------+ | xyStartRx | Start XMODEM or YMODEM receive. | +-----------+-------------------------------------------------------+ SYNTAX function xyStartRx(Port:Integer;Filename:PChar; NCGchar:Char;Batch:Integer):Integer; (* Port : Port to use. *) (* Filename : File to receive (XMODEM only). *) (* NCGchar : NAK, 'C', or 'G'. *) (* Batch : YMODEM flag (T/F). *) REMARK The xyStartRx starts the XMODEM or YMODEM file receive. Once started, calls to xyDriver are made to execute the next state (or states). The xyStartTx function returns immediately. Protocol : NCGchar BatchFlag : Comments XMODEM : NAK FALSE Standard XMODEM XMODEM/CRC : 'C' FALSE XMODEM/1K : 'C' FALSE YMODEM : 'C' TRUE Standard YMODEM The xyStart function is used to receive a file using XMODEM or YMODEM. RETURN =0 : No error (XY_NO_ERROR). <0 : Driver error. See "XYDRV Error Codes". OTHER See xyStartTx and xyDriver. +-----------+-------------------------------------------------------+ | xyStartTx | Start XMODEM or YMODEM transmit. | +-----------+-------------------------------------------------------+ SYNTAX function xyStartTx(Port:Integer;Filename:PChar;OneK:Integer; Batch:Integer); (* Port : Port to use. *) (* Filename : File to send. *) (* OneK : Want 1K blocks (T/F). *) (* Batch : YMODEM flag (T/F). *) REMARK The xyStartTx starts the XMODEM or YMODEM file send. Once started, calls to xyDriver are made to execute the next state (or states). The xyStartTx function returns immediately. Protocol : OneKflag BatchFlag : Comments XMODEM : FALSE FALSE Standard XMODEM XMODEM/CRC : FALSE FALSE XMODEM/1K : TRUE FALSE YMODEM : TRUE TRUE Standard YMODEM RETURN =0 : No error (XY_NO_ERROR). <0 : Driver error. See "XYDRV Error Codes". OTHER See xyStartRx and xyDriver. WSC4D Reference Manual Page 26 XYDRV Error Codes Error codes are always negative, except for 'no error'. Most of these error conditions rarely occur. Also note that XYDRV functions can return WSC errors. An error message is queued when an error occurs which can be retrieved with xyGetMessage. The numeric values for error codes can be found in XYDRV.PAS. +--------------------------+----------------------------------------+ | XY_NO_ERROR | No error. (0) | | XY_UNKNOWN_ERROR | Unknown error. | | XY_ALREADY_ACTIVE_ERROR | Port already acquired. | | XY_CANNOT_OPEN_ERROR | Cannot open specifed file. | | XY_EMPTY_FILE_ERROR | Specified file is empty. | | XY_NO_STARTUP_CHAR_ERROR | Must specify NAK, 'C', or 'G'. | | XY_NOT_NCG_ERROR | Expected NAK, 'C', or 'G'. | | XY_DISK_READ_ERROR | Error reading disk. | | XY_NO_EOT_ACK_ERROR | EOT was not ACKed. | | XY_INTERNAL_ERROR | Internal error! | | XY_CANCELLED_ERROR | Other side cancelled. | | XY_OUT_OF_SYNC_ERROR | Protocol has lost synchronization. | | XY_RETRIES_ERROR | Packet retry limit was exceeded. | | XY_BAD_PACKET_NBR_ERROR | Incorrect packet number. | | XY_TIMED_OUT_ERROR | Timed out waiting for other side. | | XY_NO_SUCH_FILE_ERROR | No such file. | | XY_NOT_ACTIVE_ERROR | Port not acquired by xyAcquire. | | XY_PORT_RANGE_ERROR | Port number out of range. | +--------------------------+----------------------------------------+ WSC4D Reference Manual Page 27 +----------+--------------------------------------------------------+ | ascAbort | Aborts the Ascii state driver. | +----------+--------------------------------------------------------+ SYNTAX function ascAbort:Integer; REMARK The ascAbort function forces the ASCII driver to IDLE, terminating any file transfer which may be in progress. RETURN none. +-----------+-------------------------------------------------------+ | ascDriver | Ascii state driver. | +-----------+-------------------------------------------------------+ SYNTAX function ascDriver:Integer; RETURN 1 : IDLE (A transfer is not underway). 0 : Running (A transfer is underway). REMARK The ascDriver function drives the state engine. It executes the next driver state, and is typically called from within a timer loop. ascDriver can be called as often as wanted whether or not a file transfer was initiated. Note that ascDriver never returns an error code. OTHER See ascStartTx and ascStartRx. WSC4D Reference Manual Page 28 +---------------+---------------------------------------------------+ | ascGetMessage | Get next Ascii driver message. | +---------------+---------------------------------------------------+ SYNTAX function ascGetMessage(Buffer:PChar;Size:Integer):Integer; (* Buffer : Message buffer. *) (* Size : Size of message buffer. *) REMARK The ascGetMessage function retieves the next message from the driver message queue. Refer to the program TERM_PGM.PAS for an example of using ascGetMessage. RETURN TRUE : A message was copied into Buffer. FALSE : No messages are available. OTHER See ascGetParameter. +-----------------+-------------------------------------------------+ | ascGetParameter | Retrieves driver parameter. | +-----------------+-------------------------------------------------+ SYNTAX function ascGetParameter(Parameter:Integer):Integer; (* Parameter : Parameter to return. *) REMARK The driver parameter corresponding to the following table is returned. Parameter : Desciption ASC_GET_ERROR_CODE : Driver error code (see ASDRV.PAS) ASC_GET_ERROR_STATE : Error state (if in error). ASC_GET_STATE : Current state (ss ASDRV.PAS). -1 : Cannot recognize parameter. The ascGetParameter function can be used to check the state of the driver. For example: (1) ascGetParameter(Port,ASC_GET_STATE) returns the current state. (2) ascGetParameter(Port,ASC_GET_ERROR_CODE) returns the driver error code if an error has occurred or ASC_NO_ERROR (0) otherwise. RETURN See above. WSC4D Reference Manual Page 29 +---------+---------------------------------------------------------+ | ascInit | Start Ascii receive. | +---------+---------------------------------------------------------+ SYNTAX function ascInit(Port,RxBufSize,xFlag:Integer):Integer; (* Port : Port selected. *) (* RxBufSize : RX buffer size *) (* xFlag : Perform XON/XOFF flag (T/F). *) REMARK The ascInit initializes the Ascii driver for subsequent use. RxBufSize is the size of the receive buffer as passed to SioReset. xFlag is used to request that XON/XOFF flow control be performed by the Ascii driver. RETURN =0 : No error (ASC_NO_ERROR). <0 : Driver error. See "Error Codes" for a list of errors. OTHER See ascStartTx and ascDriver. +------------+------------------------------------------------------+ | ascStartRx | Start Ascii receive. | +------------+------------------------------------------------------+ SYNTAX function ascStartRx(FileName:PChar; TermChar:Integer; FirstWait,CharWait:Integer; EchoFlag:Integer):Integer; (* Filename : File to receive *) (* TermChar : Termination character ($00 if none) *) (* FirstWait: Max seconds to wait for 1st incoming char *) (* CharWait : Max seconds between chars to wait *) (* EchoFlag : Echo to display if true *) REMARK The ascStartRx starts the ASCII file receive. Once started, calls to ascDriver are made to execute the next state (or states). The ascStartTx function returns immediately. You may need to prompt the sender by sending a carriage return ($0d) or XON character ($11). See TERM_PGM.PAS for an example. RETURN =0 : No error (ASC_NO_ERROR). <0 : Driver error. See "Error Codes" for a list of errors. OTHER See ascStartTx and ascDriver. WSC4D Reference Manual Page 30 +------------+------------------------------------------------------+ | ascStartTx | Start Ascii transmit. | +------------+------------------------------------------------------+ SYNTAX function ascStartTx(FileName:PChar; CharPace:Integer; TermChar,EchoFlag:Integer):Integer; (* Filename : File to receive *) (* CharPace : Delay in millisecs between chars *) (* TermChar : Termination character ($00 if none) *) (* EchoFlag : Echo to display if true *) REMARK The ascStartTx starts the Ascii file send. Once started, calls to ascDriver are made to execute the next state (or states). The ascStartTx function returns immediately. RETURN =0 : No error (ASC_NO_ERROR). <0 : Driver error. See XYDRV.PAS for a list of errors. OTHER See ascStartRx and ascDriver. ASDRV Error Codes Error codes are always negative, except for 'no error'. Most of these error conditions rarely occur. Also note that ASCII DRIVER functions can return WSC errors. An error message is queued when an error occurs which can be retrieved with ascGetMessage. The numeric values for error codes can be found in ASDRV.PAS. +------------------------+------------------------------------------+ | ASC_NO_ERROR | No error. (0) | | ASC_NOT_ACTIVE_ERROR | ascInit not previously called. | | ASC_CANNOT_OPEN_ERROR | Cannot open specifed file. | | ASC_DISK_IO_ERROR | Error reading or writting disk. | | ASC_INTERNAL_ERROR | Internal error! | | ASC_NOT_OPEN_ERROR | File not open. | +------------------------+------------------------------------------+ WSC4D Reference Manual Page 31